1. Autorización
Una vez capturados los datos de la tarjeta en su aplicación, puede enviarlos a Addon Payments para que se verifiquen, saneen y formateen de la forma correcta para su porterior procesamiento en nuestros servidores. Los comercios que capturan datos en su aplicación (y en su servidor) deben ser conscientes de sus responsabilidades de cumplimiento de PCI DSS.
Recomendamos encarecidamente sanear los datos del titular de la tarjeta antes de enviarla en la solicitud. Por ejemplo, debe comprobar que el número de tarjeta es válido y que la fecha de caducidad es correcta. Nuestra biblioteca JS contiene un conjunto de funciones útiles que le ayudan a procesar las solicitudes correctamente. --> En los ejemplos de esta documentación usamos el fichero de comprobación JS rxp-js.js de RealexPayments. Podrá ver el fichero en la carpeta de "assets/js".
1.0.1 URL de notificación
Lo primero que debemos hacer antes de probar o implementar 3D Secure 2 es instalar y configurar los endpoints en su sitio web que recibirán notificaciones de eventos y datos del servidor de control de acceso del emisor (ACS). Debe ser capaz de aceptar HTTP POST con valores codificados en Base64url. Se utiliza en dos momentos clave durante la autenticación:
- Finalización del método 3DS: Este endpoint le indica a su sitio web que el ACS ha completado la creación de perfiles del navegador. El método POST simplemente contiene el identificador único de Addon Payments para la autenticación 3D Secure (ID de transacción del servidor).
- Finalización del desafío ACS: Este endpoint le indica a su sitio web que el desafío presentado al cliente se ha completado. La petición POST también contiene datos clave de autenticación, incluido si el cliente se autenticó correctamente o no.
1.0.2 Notificación método 3DS
<?php
// Los ejemplos de código que no pertenecen al SDK que se utilizan en este artículo son ejemplos simples y no deben usarse como código listo para producción.
$threeDSMethodData = $_REQUEST["threeDSMethodData"];
// Lanzamos la petición al servidor de Addon Payments
try {
$decodedThreeDSMethodData = base64_decode($threeDSMethodData);
$convertedThreeDSMethodData = json_decode($decodedThreeDSMethodData, true);
// Obtenemos la respuesta y la mostramos
echo "<div id='transID'>.json_encode($convertedThreeDSMethodData).</div>;
} catch (Exception $e) {
// Añada aquí su tratamiento de errores
echo $e->getMessage();
}
?>
1.0.3 Notificación del desafío ACS
<?php
// Los ejemplos de código que no pertenecen al SDK que se utilizan en este artículo son ejemplos simples y no deben usarse como código listo para producción.
$cres = $_REQUEST["cres"];
// Lanzamos la petición al servidor de Addon Payments
try {
$decodedString = base64_decode($cres);
// Obtenemos la respuesta y la mostramos
echo "<div id='respuestaAcs'>.$decodedString.</div>;
} catch (Exception $e) {
// Añada aquí su tratamiento de errores
echo $e->getMessage();
}
?>
2. Recopilar información del dispositivo
En la primera solicitud para iniciar 3D Secure 2 (iniciar la autenticación) además de los detalles de facturación y envío del cliente y la información de la transacción, también debemos proporcionar los datos del navegador. Puede recopilar estos datos independientemente del proceso de autenticación de 3D Secure, por ejemplo, cuando ingrese el cliente en su web.
Algunos dispositivos pueden devolver una profundidad de color que no está en la lista de valores aceptados, en este escenario EMVCo. La recomendación es enviar el valor más bajo más cercano, por ejemplo, si la profundidad de color devuelta por el navegador es 30, envíe 24 ya que este es el valor más bajo más cercano.
En nuestros ejemplos a continuación, recopilamos tantos datos como podamos en el lado del cliente utilizando JavaScript. Para algunas de las variables (browserLanguage, userAgent y timeZoneOffSet) también puede usar métodos del lado del servidor.
<script>
function gatherBrowserData() {
var colorDepth = screen.colorDepth; // 24
var javaEnabled = navigator.javaEnabled(); // true
var browserLanguage = navigator.language; // en_US
var screenHeight = screen.height; // 1080
var screenWidth = screen.width; // 1920
var userAgent = navigator.userAgent;
// Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.110 Safari/537.36
var browserTime = new Date();
var browserTimezoneZoneOffset = (browserTime.getTimezoneOffset() / 60); // 0
}
</script>
Muestra del lado servidor
<?php
$customerIp = $_SERVER["REMOTE_ADDR"]; // 123.123.123.123
$acceptHeader = $_SERVER["HTTP_ACCEPT"];
// text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8
?>
3. Comprobar la versión
El primer paso es verificar la versión que admite la tarjeta. Addon Payments mantiene una base de datos actualizada de los rangos de BIN y las versiones de 3D Secure que admiten.
Si la tarjeta está inscrita en 3D Secure 2, se devolverá la versión exacta (2.xx) junto con la URL necesaria para facilitar la recopilación de datos del dispositivo por parte del Emisor ACS (si es compatible). Si la tarjeta no está inscrita, el único valor devuelto será inscrito = falso. En este escenario, puede proceder a verificar si la tarjeta está inscrita en 3D Secure 1. Para obtener más información consulte la documentación de 3D Secure 1.
<?php
// Imports necesarios para comprobar la versión
require_once('vendor/autoload.php');
use AddonPayments\Api\ServicesConfig;
use AddonPayments\Api\ServicesContainer;
use AddonPayments\Api\Services\Secure3dService;
use AddonPayments\Api\Entities\Exceptions\ApiException;
use AddonPayments\Api\PaymentMethods\CreditCardData;
use AddonPayments\Api\Entities\Enums\Secure3dVersion;
// Configuración del terminal
$config = new ServicesConfig();
$config->merchantId = "Merchant_ID";
$config->accountId = "Sub_Account";
$config->sharedSecret = "Shared_Secret";
$config->methodNotificationUrl = "https://dominio.com/notificacion3ds.php";
$config->challengeNotificationUrl = "https://dominio.com/notificacionAcs.php";
$config->merchantContactUrl = "https://dominio.com/about";
$config->secure3dVersion = Secure3dVersion::TWO;
ServicesContainer::configure($config);
// Creamos el objeto tarjeta
$card = new CreditCardData();
$card->number = "4263970000005262";
// Lanzamos la petición al servidor de Addon Payments
try {
$threeDSecureData = Secure3dService::checkEnrollment($card)->execute("TWO", Secure3dVersion::TWO);
// Obtenemos la respuesta y la mostramos
echo json_encode($threeDSecureData);
} catch (ApiException $e) {
// Añada aquí su tratamiento de errores
echo $e->getMessage();
}
?>
4. Obtener la infromación
Si el Emisor ACS admite la recopilación de datos del dispositivo, en la respuesta a la verificación de versión se devolverá la URL del Método ACS. En el lado del cliente, debemos abrir un iFrame oculto dirigido a la URL del método 3DS ACS enviando el objeto de datos del método 3DS.
El objeto de datos del método 3DS es un objeto JSON codificado en Base64url que contiene el ID de transacción del servidor y la URL de notificación del método. Esto se devolvió en respuesta a la verificación de la versión de 3D Secure.
En caso de que el Emisor ACS no admita datos del dispositivo, no se devolverá la URL del método y podrá pasar al siguiente paso mientras configura el indicador de finalización del método 3DS como no disponible.
<script>
var form = document.createElement("form");
form.setAttribute("method", "POST");
form.setAttribute("action", "https://www.acsurl.com/method");
form.setAttribute("id", "formIframe");
form.setAttribute("target", "hidden_iframe");
var threeDSMethodData = document.createElement("input");
threeDSMethodData.setAttribute("type", "hidden");
threeDSMethodData.setAttribute("name", "threeDSMethodData");
// Añadir el JSON devuelto por Addon Payments
threeDSMethodData.setAttribute("value", threeDSmethodDataObject);
form.appendChild(threeDSMethodData);
document.body..appendChild(form);
form.submit();
</script>
Si la URL del método ACS recopila correctamente la información del dispositivo, en el iFrame enviará un formulario POST y redirigirá el navegador a su URL de notificación. Su código del lado del cliente podrá detectar la redirección y cerrar el iFrame oculto en consecuencia. La recopilación de datos del dispositivo debe completarse en segundos, lo que permite que su aplicación continúe con el siguiente paso, estableciendo el indicador de finalización del método 3DS en verdadero.
Si la recopilación de información del dispositivo no tiene éxito, el tiempo de espera máximo establecido por el ACS es de 10 segundos. Sin embargo, es posible que desee continuar con el siguiente paso antes. En este caso, su aplicación debe cerrar el iFrame dentro de su período de tiempo determinado (por ejemplo, 3 segundos) y establecer el indicador de finalización del método 3DS en Falso en la siguiente solicitud.
5. Iniciar autenticación
Suponiendo que ya haya recopilado los datos relevantes del dispositivo y (condicionalmente) que el proceso de URL del método ACS esté completo, su aplicación ahora puede iniciar la autenticación 3D Secure 2. A continuación, describimos los datos requeridos y recomendados que se enviarán en la petición POST al endpoint de autenticación. Esto incluye los detalles de facturación y envío del cliente, al menos un número de teléfono, los datos del dispositivo y los detalles de la transacción (importe, moneda, etc.).
También debe incluir la URL de notificación del ACS (1.0.3 Notificación del desafío ACS) de su aplicación, una bandera que indique el resultado de la URL del método ACS (o si tuvo lugar) y un enlace a una página "Acerca de" o "Contacto" de su sitio web con información de atención al cliente.
5.1 Exenciones
Una de las ventajas clave de 3D Secure 2 es que proporciona un marco para que los comerciantes se beneficien de las exenciones de SCA en determinadas condiciones. La idea detrás de estas exenciones es permitir el desarrollo de una experiencia de pago fácil de usar en circunstancias donde el riesgo es bajo.
El Emisor puede aplicar exenciones en función de los detalles de la transacción o el comerciante puede solicitarlas específicamente, con el permiso de su adquirente. En el mensaje de autenticación, puede solicitar una exención incluyéndola en el campo Indicador de solicitud de desafío (consulte la nota a continuación).
Cuando un comercio solicita una exención, ya no podrá hacer uso de un cambio de responsabilidad en caso de una devolución de cargo. --> Para solicitudes de exención de Mastercard, consulte también nuestra documentación de mensajes de Mastercard.
5.2 Solicitud de muestra
En este ejemplo, solo estamos pasando campos obligatorios junto con algunos recomendados. Cuantos más campos opcionales envíe y los datos que proporcione, es más probable que la autenticación de la transacción sea fluida.
<?php
// Imports necesarios
require_once('vendor/autoload.php');
use AddonPayments\Api\ServicesConfig;
use AddonPayments\Api\ServicesContainer;
use AddonPayments\Api\Services\Secure3dService;
use AddonPayments\Api\Entities\Exceptions\ApiException;
use AddonPayments\Api\Entities\Enums\ColorDepth;
use AddonPayments\Api\PaymentMethods\CreditCardData;
use AddonPayments\Api\Entities\Enums\Secure3dVersion;
use AddonPayments\Api\Entities\ThreeDSecure;
use AddonPayments\Api\Entities\Address;
use AddonPayments\Api\Entities\BrowserData;
use AddonPayments\Api\Entities\Enums\AddressType;
use AddonPayments\Api\Entities\Enums\ChallengeWindowSize;
use AddonPayments\Api\Entities\Enums\MethodUrlCompletion;
// Configuración del terminal
$config = new ServicesConfig();
$config->merchantId = "Merchant_ID";
$config->accountId = "Sub_Account";
$config->sharedSecret = "Shared_Secret";
$config->methodNotificationUrl = "https://dominio.com/notificacion3ds.php";
$config->challengeNotificationUrl = "https://dominio.com/notificacionAcs.php";
$config->merchantContactUrl = "https://dominio.com/about";
$config->secure3dVersion = Secure3dVersion::TWO;
ServicesContainer::configure($config);
// Creamos el objeto tarjeta
$card = new CreditCardData();
$card->number = "4263970000005262";
$card->expMonth = "05";
$card->expYear = "25";
$card->cvn = "123";
$card->cardHolderName = "Víctor Cantera";
// Creamos el objeto de facturación
$billingAddress = new Address();
$billingAddress->streetAddress1 = "Dirección de facturación 1";
$billingAddress->streetAddress2 = "Dirección de facturación 2";
$billingAddress->streetAddress3 = "Dirección de facturación 3";
$billingAddress->city = "Ciudad";
$billingAddress->state = "País";
$billingAddress->postalCode = "Código Postal";
$billingAddress->countryCode = "ISO del país (ES, GB, US...)";
// Creamos el objeto de envío
$shippingAddress = new Address();
$shippingAddress->streetAddress1 = "Dirección de envío 1";
$shippingAddress->streetAddress2 = "Dirección de envío 2";
$shippingAddress->streetAddress3 = "Dirección de envío 3";
$shippingAddress->city = "Ciudad";
$shippingAddress->postalCode = "Código Postal";
$shippingAddress->countryCode = "ISO del país (ES, GB, US...)";
// Capturamos la información del navegador del cliente
$browserData = new BrowserData();
$browserData->acceptHeader = "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8";
$browserData->colorDepth = ColorDepth::TWENTY_FOUR_BITS;
$browserData->ipAddress = "123.123.123.123";
$browserData->javaEnabled = TRUE;
$browserData->language = "es";
$browserData->screenHeight = "1080";
$browserData->screenWidth = "1920";
$browserData->challengWindowSize = ChallengeWindowSize::FULL_SCREEN;
$browserData->timeZone = "0";
$browserData->userAgent = "Mozilla/5.0 (Windows NT 6.1; Win64, x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.110 Safari/537.36";
// Indicamos el ID de transacción del servidor
$threeDSecureData = new ThreeDSecure();
$threeDSecureData->serverTransactionId = "9de5bccf-c438-4024-8961-ec4b3cff15ff";
// Lanzamos la petición al servidor de Addon Payments
try {
$threeDSecureData = Secure3dService::initiateAuthentication($card, $threeDSecureData)
->withAmount(10)
->withCurrency("EUR")
->withOrderCreateDate(date("Y-m-d H:i:s"))
->withCustomerEmail("victor.cantera@example.com")
->withAddress($billingAddress, AddressType::BILLING)
->withAddress($shippingAddress, AddressType::SHIPPING)
->withBrowserData($browserData)
->withMethodUrlCompletion(MethodUrlCompletion::YES)
->withMobileNumber("34", "914353028")
->execute(Secure3dVersion::TWO);
// Obtenemos la respuesta y la mostramos
echo json_encode($threeDSecureData);
} catch (ApiException $e) {
// Añada aquí su tratamiento de errores
echo $e->getMessage();
}
?>
5.3 Campos opcionales
3D Secure 2 permite el envío de un conjunto de datos mucho mayor que su predecesor. Cuantos más datos se envíen, más información tendrá el Emisor al tomar la decisión de si la autenticación de la transacción debe realizarse a través de un flujo sin fricción o de desafío.
<?php
// Imports necesarios para los datos adicionales
require_once('vendor/autoload.php');
use AddonPayments\Api\Services\Secure3dService;
use AddonPayments\Api\Entities\Enums\Secure3dVersion;
use AddonPayments\Api\Entities\Enums\AgeIndicator;
use AddonPayments\Api\Entities\Enums\AuthenticationRequestType;
use AddonPayments\Api\Entities\Enums\CustomerAuthenticationMethod;
use AddonPayments\Api\Entities\Enums\DeliveryTimeFrame;
use AddonPayments\Api\Entities\Enums\OrderTransactionType;
use AddonPayments\Api\Entities\Enums\PreOrderIndicator;
use AddonPayments\Api\Entities\Enums\PriorAuthenticationMethod;
use AddonPayments\Api\Entities\Enums\ReorderIndicator;
use AddonPayments\Api\Entities\Enums\ShippingMethod;
// Datos obligatorios para la autenticación 3DS2
$threeDSecureData = Secure3dService::initiateAuthentication($card, $threeDSecureData)
->withAmount(10)
->withCurrency("EUR")
->withOrderCreateDate(date("Y-m-d H:i:s"))
->withCustomerEmail("victor.cantera@example.com")
->withAddress($billingAddress, AddressType::BILLING)
->withAddress($shippingAddress, AddressType::SHIPPING)
->withBrowserData($browserData)
->withMethodUrlCompletion(MethodUrlCompletion::YES)
->withMobileNumber("34", "914353028")
// Datos adicionales
->withHomeNumber("34", "914353028")
->withWorkNumber("34", "914353028")
->withMerchantInitiatedRequestType(AuthenticationRequestType::RECURRING_TRANSACTION)
// Información de tarjeta regalo
->withGiftCardCount(1)
->withGiftCardCurrency("EUR")
->withGiftCardAmount(5)
// Información adicional de la orden
->withDeliveryEmail("victor.cantera@example.com")
->withDeliveryTimeFrame(DeliveryTimeFrame::ELECTRONIC_DELIVERY)
->withShippingMethod(ShippingMethod::VERIFIED_ADDRESS)
->withShippingNameMatchesCardHolderName(TRUE)
->withPreOrderIndicator(PreOrderIndicator::MERCHANDISE_AVAILABLE)
->withPreOrderAvailabilityDate(date("Y-m-d H:i:s"))
->withReorderIndicator(ReorderIndicator::FIRST_TIME_ORDER)
->withOrderTransactionType(OrderTransactionType::GOODS_SERVICE_PURCHASE)
// Información adicional del pagador
->withCustomerAccountId("6dcb24f5-74a0-4da3-98da-4f0aa0e88db3")
->withAccountAgeIndicator(AgeIndicator::LESS_THAN_THIRTY_DAYS)
->withAccountCreateDate(date("Y-m-d H:i:s"))
->withAccountChangeDate(date("Y-m-d H:i:s"))
->withAccountChangeIndicator(AgeIndicator::THIS_TRANSACTION)
->withPasswordChangeDate(date("Y-m-d H:i:s"))
->withPasswordChangeIndicator(AgeIndicator::LESS_THAN_THIRTY_DAYS)
->withPaymentAccountCreateDate(date("Y-m-d H:i:s"))
->withPaymentAccountAgeIndicator(AgeIndicator::LESS_THAN_THIRTY_DAYS)
->withPreviousSuspiciousActivity(false)
->withNumberOfPurchasesInLastSixMonths(3)
->withNumberOfTransactionsInLast24Hours(1)
->withNumberOfTransactionsInLastYear(5)
->withNumberOfAddCardAttemptsInLast24Hours(1)
->withShippingAddressCreateDate(date("Y-m-d H:i:s"))
->withShippingAddressUsageIndicator(AgeIndicator::THIS_TRANSACTION)
// Datos adicionales Prior 3DS2
->withPriorAuthenticationMethod(PriorAuthenticationMethod::FRICTIONLESS_AUTHENTICATION)
->withPriorAuthenticationTransactionId("26c3f619-39a4-4040-bf1f-6fd433e6d615")
->withPriorAuthenticationTimestamp(date("Y-m-d H:i:s"))
->withPriorAuthenticationData("cKTYtrvvKU7gUoiqbbO7Po")
// Datos adicionales de petición recurrente
->withMaxNumberOfInstallments(5)
->withRecurringAuthorizationFrequency(25)
->withRecurringAuthorizationExpiryDate(date("Y-m-d H:i:s"))
// Datos adicionales del login del pagador
->withCustomerAuthenticationMethod(CustomerAuthenticationMethod::MERCHANT_SYSTEM)
->withCustomerAuthenticationTimestamp(date("Y-m-d H:i:s"))
->execute(Secure3dVersion::TWO)
Puede ver la información detallada de cada propiedad en la documentación oficial.
6. Flujos de autenticación
En este punto, el Emisor analizará la transacción. Tendrá en cuenta factores como los datos que su aplicación ha proporcionado junto con el comportamiento histórico del cliente y el análisis de transacciones. El resultado de este proceso determinará si el Emisor decide que el cliente debe autenticar aún más la transacción y realizar una comprobación con el ACS (flujo con fricción).
6.1 Flujo sin fricción
En un flujo sin fricciones, el Emisor puede determinar que no se requiere ningún desafío para autenticar la transacción. O que en base a la información que ha recibido hasta ahora, la transacción no debería continuar. Para los comerciantes europeos y las transacciones dentro del alcance de PSD2, el Emisor también verificará que se pueda aplicar una exención válida.
Dependiendo del resultado y del valor de ECI relevante, su aplicación ahora puede proceder a la autorización o mostrar un mensaje al cliente indicándole que su transacción no se realizó correctamente y devolverlo a la página de pago.
A continuación mostramos una respuesta de autenticación exitosa.
<?php
require_once('vendor/autoload.php');
$status = $threeDSecureData->status; // AUTHENTICATION_SUCCESSFUL
// Datos requeridos para la autorización
$authenticationValue = $threeDSecureData->authenticationValue; // ODQzNjgwNjU0ZjM3N2JmYTg0NTM=s
$dsTransId = $threeDSecureData->directoryServerTransactionId; // c272b04f-6e7b-43a2-bb78-90f4fb94aa25
$messageVersion = $threeDSecureData->messageVersion; // 2.1.0
$eci = $threeDSecureData->eci; // 05
// Información adicional
$acsTransID = $threeDSecureData->acsTransactionId; // 13c701a3-5a88-4c45-89e9-ef65e50a8bf9
$statusReason = $threeDSecureData->statusReason; // LOW_CONFIDENCE
$authenticationSource = $threeDSecureData->authenticationSource; // BROWSER
$messageCategory = $threeDSecureData->messageCategory; // PAYMENT_AUTHENTICATION
?>
A continuación mostramos una respuesta de autenticación fallida.
<?php
require_once('vendor/autoload.php');
$status = $threeDSecureData->status; // AUTHENTICATION_FAILED
// Datos requeridos para la autorización
$authenticationValue = $threeDSecureData->authenticationValue; // ODQzNjgwNjU0ZjM3N2JmYTg0NTM=s
$dsTransId = $threeDSecureData->directoryServerTransactionId; // c272b04f-6e7b-43a2-bb78-90f4fb94aa25
$messageVersion = $threeDSecureData->messageVersion; // 2.1.0
$eci = $threeDSecureData->eci; // 07
// Información adicional
$acsTransID = $threeDSecureData->acsTransactionId; // 13c701a3-5a88-4c45-89e9-ef65e50a8bf9
$statusReason = $threeDSecureData->statusReason; // CARD_AUTHENTICATION_FAILED
$authenticationSource = $threeDSecureData->authenticationSource; // BROWSER
$messageCategory = $threeDSecureData->messageCategory; // PAYMENT_AUTHENTICATION
?>
6.2 Flujo con fricción
El Emisor determina que se requiere una autenticación adicional para que la transacción continúe. Esto puede deberse a varias razones, incluida una transacción de alto valor, un comportamiento de pago inusual para este cliente en particular (hora del día, tipo de comerciante, etc.) o no coinciden/no se han enviado datos suficientes para que tomen una determinación.
La solución de Addon Payments formateará el del desafío con fricción y lo devolverá a su solicitud para que lo envíe al Emisor ACS. La Solicitud de fricción está compuesta por varias variables de transacción, incluidos los identificadores para la autenticación (ID de transacción del servidor, ID de transacción de ACS y el tamaño de la ventana de fricción).
Respuesta al desafío
<?php
require_once('vendor/autoload.php');
// Datos requeridos para mostrar el intercambio al cliente
$challengeRequestUrl = $threeDSecureData->issuerAcsUrl; // https://test.portal.gpwebpay.com/pay-sim-gpi/sim/acs
$encodedCreq = $threeDSecureData->payerAuthenticationRequest; // String en base64=s
// Información adicional
$authenticationType = $threeDSecureData->authenticationType; // DYNAMIC_CHALLENGE
$challengeMandated = $threeDSecureData->challengeMandated; // true
$statusReason = $threeDSecureData->statusReason; // LOW_CONFIDENCE
$authenticationSource = $threeDSecureData->authenticationSource; // BROWSER
$messageCategory = $threeDSecureData->messageCategory; // PAYMENT_AUTHENTICATION
$dsTransId = $threeDSecureData->directoryServerTransactionId; // c272b04f-6e7b-43a2-bb78-90f4fb94aa25
$acsTransID = $threeDSecureData->acsTransactionId; // 13c701a3-5a88-4c45-89e9-ef65e50a8bf9
$messageVersion = $threeDSecureData->messageVersion; // 2.1.0
?>
7. Desafío ACS
Para facilitar la autenticación, su aplicación/sitio web deberá abrir la URL ACS en un iFrame. El contenido del iFrame se formateará de acuerdo con el parámetro de tamaño de la ventana de desafío indicado en la solicitud de autenticación.
<script>
var form = document.createElement("form");
form.setAttribute("method", "POST");
form.setAttribute("action", "https://www.acs.com/challenge");
form.setAttribute("target", "iframe");
var creqData = document.createElement("input");
threeDSMethodData.setAttribute("type", "hidden");
threeDSMethodData.setAttribute("name", "creq");
// Añadir el objeto "creq" obtenido del servidor
creqData.setAttribute("value", creqObject);
form.appendChild(creqData);
document.body..appendChild(form);
form.submit();
</script>
El Emisor ACS determinará el tipo de desafío que se mostrará al cliente y se alineará con al menos dos elementos de la autenticación del cliente:
- Possession: Algo que solo el cliente tiene, por ejemplo, su dispositivo móvil registrado en su banco en el que recibirá un código en un SMS.
- Inherence: Su huella digital u otra forma de datos biométricos.
- Knowledge: Una frase de contraseña única o la respuesta a una pregunta personal.
Con el cliente en el ACS, pueden ocurrir los siguientes resultados:
- La autenticación es exitosa: Transaction Status = Y
- La autenticación falla y el cliente no tiene otra oportunidad: Transaction Status = N
- La autenticación falla y el cliente tiene otra oportunidad
Una vez que el cliente completa el desafío (independientemente del resultado), el ACS realiza dos acciones:
- Primero: Informa a Addon Payments 3DS Solution del resultado y transmite las variables de autenticación.
- Segundo: Al igual que con la URL del método ACS, enviará un mensaje de POST y redirigirá el navegador a su URL de notificación con el Resultado del desafío (CRes). Su código del lado del cliente podrá detectar la redirección.
Addon Payments proporciona un simulador Emisor ACS que le permite probar diferentes resultados de desafíos.
7.1 Simulador ACS
En el entorno sandbox (pruebas), Addon Payments proporciona un simulador de Emisor ACS que le permite probar diferentes resultados de desafíos.
Una vez que se haya cargado el desafío, después de diez segundos, el simulador completará automáticamente la autenticación y generará una respuesta de Autenticación exitosa (transStatus = “Y”). Esto tiene la intención de imitar un escenario en el que un cliente ha recibido una notificación en su teléfono para autenticarse usando su aplicación bancaria.
Para simular una autenticación fallida, hacer clic en el botón "Cancelar" generará una respuesta fallida (transStatus = “N”). En cualquier escenario, el resultado se enviará en el mensaje de respuesta de desafío (CRes) al punto final de notificación de desafío.
8. Obtener datos de autenticación
Si la transacción se autentica correctamente (Transaction Status = Y), el paso final antes de procesar la autorización es obtener los datos de autenticación necesarios de la solución Addon Payments 3DS. Estos son los datos que el ACS pasó a Addon Payments cuando el cliente completó el desafío.
Para hacer esto, llamamos al endpoint de autenticación con el ID de transacción del servidor 3DS relevante:
- https://api.sandbox.globalpay-ecommerce.com/3ds2/authentications/{server_trans_id}?merchant_id={merchant_id}&request_timestamp={request_timestamp}
Si el cliente canceló la transacción durante el desafío o la autenticación no procedió por otro motivo, el endpoint de resumen también le proporcionará la información disponible para que pueda actualizar su aplicación/sitio web en consecuencia.
La información más importante que necesitamos para la autorización es el ECI y el valor de autenticación.
<?php
// Imports necesarios
require_once('vendor/autoload.php');
use AddonPayments\Api\ServicesConfig;
use AddonPayments\Api\ServicesContainer;
use AddonPayments\Api\Services\Secure3dService;
use AddonPayments\Api\Entities\Enums\Secure3dVersion;
use AddonPayments\Api\Entities\Exceptions\ApiException;
// Configuración del terminal
$config = new ServicesConfig();
$config->merchantId = "Merchant_ID";
$config->accountId = "Sub_Account";
$config->sharedSecret = "Shared_Secret";
$config->methodNotificationUrl = "https://dominio.com/notificacion3ds.php";
$config->challengeNotificationUrl = "https://dominio.com/notificacionAcs.php";
$config->merchantContactUrl = "https://dominio.com/about";
$config->secure3dVersion = Secure3dVersion::TWO;
ServicesContainer::configure($config);
// Lanzamos la petición al servidor de Addon Payments
try {
$threeDSecureData = Secure3dService::getAuthenticationData()
->withServerTransactionId(6c8c286b-9842-4c74-b298-da640da6ebbd)
->execute(Secure3dVersion::TWO);
} catch (ApiException $e) {
// Añada aquí su tratamiento de errores
echo $e->getMessage();
}
echo json_encode($threeDSecureData);
?>
9. Autorización
Si está procesando el pago con Addon Payments una vez que el proceso 3D Secure esté completo y dependiendo del valor ECI devuelto, podemos proceder con la autorización incluyendo los datos de autenticación. La transacción se procesará con normalidad y puede tener éxito o rechazarse según criterios estándar (fondos suficientes, código de seguridad correcto ingresado...).
<?php
// Imports necesarios
require_once('vendor/autoload.php');
use AddonPayments\Api\ServicesConfig;
use AddonPayments\Api\ServicesContainer;
use AddonPayments\Api\Entities\Exceptions\ApiException;
use AddonPayments\Api\PaymentMethods\CreditCardData;
use AddonPayments\Api\Entities\ThreeDSecure;
// Configuración del terminal
$config = new ServicesConfig();
$config->merchantId = "Merchant_ID";
$config->accountId = "Sub_Account";
$config->sharedSecret = "Shared_Secret";
$config->serviceUrl = "https://api.sandbox.realexpayments.com/epage-remote.cgi";
ServicesContainer::configure($config);
// Creamos el objeto tarjeta
$card = new CreditCardData();
$card->number = "4263970000005262";
$card->expMonth = "05";
$card->expYear = "25";
$card->cvn = "123";
$card->cardHolderName = "Víctor Cantera";
// Indicamos la información obtenida en la autenticación 3D Secure 2
$threeDSecureData = new ThreeDSecure();
$threeDSecureData->authenticationValue = "ODQzNjgwNjU0ZjM3N2JmYTg0NTM=";
$threeDSecureData->directoryServerTransactionId = "c272b04f-6e7b-43a2-bb78-90f4fb94aa25";
$threeDSecureData->eci = "5";
$threeDSecureData->messageVersion = "2.1.0";
// Añadimos los datos 3D Secure 2 al objeto de la tarjeta
$card->threeDSecure = $threeDSecureData;
// Lanzamos la petición al servidor de Addon Payments
try {
$response = $card->charge(10)
->withCurrency("EUR")
->execute();
// Obtenemos la respuesta y la mostramos
echo json_encode($response);
} catch (ApiException $e) {
// Añada aquí su tratamiento de errores
echo $e->getMessage();
}
?>
10. Formulario de ejemplo
Para poder procesar la transacción con el formulario de ejemplo, debe modificar los archivos alojados en la ruta "vendor\addonpayments\php-sdk\test\php\API\06 - 3DS2\".
Debe introducir sus datos de configuración proporcionados por el equipo de soporte de Addon Payments (email: soporte@addonpayments.com y teléfono 914353028):
- Merchant ID
- Account
- Shared Secret
- Method Notification URL (1.0.2 Notificación método 3DS)
- Challenge Notification URL (1.0.3 Notificación del desafío ACS)
- Merchant Contact URL
Para que el ejemplo funcione correctamente, debe modificar los parámetros "Method Notification URL" y "Challenge Notification URL" según la ruta de su dominio, por ejemplo, si su dominio fuese "https://dominio.com" y quisiera utilizar los arhivos ya configurados en esta guía, debería indicar la siguiente ruta:
- Method Notification URL: https://dominio.com/vendor/addonpayments/php-sdk/test/php/API/06%20-%203DS2/n3ds.php
- Challenge Notification URL: https://dominio.com/vendor/addonpayments/php-sdk/test/php/API/06%20-%203DS2/nACS.php
10.1 Formulario
El siguiente formulario le permite enviar una operación contra el entorno de pruebas de Addon Payments.